Skip to content

Conversation

@Ethan-Arrowood
Copy link
Contributor

Support an env option that is passed to the
underlying child_process.
Fixes: #60709

@nodejs-github-bot
Copy link
Collaborator

Review requested:

  • @nodejs/test_runner

@nodejs-github-bot nodejs-github-bot added needs-ci PRs that need a full CI run. test_runner Issues and PRs related to the test runner subsystem. labels Jan 13, 2026
@codecov
Copy link

codecov bot commented Jan 13, 2026

Codecov Report

❌ Patch coverage is 81.81818% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.87%. Comparing base (1bd7f62) to head (0eb68d1).
⚠️ Report is 116 commits behind head on main.

Files with missing lines Patch % Lines
lib/internal/test_runner/runner.js 81.81% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #61367      +/-   ##
==========================================
+ Coverage   88.51%   89.87%   +1.36%     
==========================================
  Files         704      671      -33     
  Lines      208739   203319    -5420     
  Branches    40274    39095    -1179     
==========================================
- Hits       184770   182742    -2028     
+ Misses      15968    12926    -3042     
+ Partials     8001     7651     -350     
Files with missing lines Coverage Δ
lib/internal/test_runner/runner.js 93.12% <81.81%> (+0.17%) ⬆️

... and 129 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

const args = getRunArgs(path, opts);
const stdio = ['pipe', 'pipe', 'pipe'];
const env = { __proto__: null, ...process.env, NODE_TEST_CONTEXT: 'child-v8' };
const env = opts.env || { __proto__: null, ...process.env, NODE_TEST_CONTEXT: 'child-v8' };
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NODE_TEST_CONTEXT is used by the test runner to identify the runner subprocesses, and removing it may cause issues with the reporters.

It must be preserved even if the user passes opts.env.

I would suggest, in any case, adding a snapshot test when using this option to cover the E2E once the option has been provided!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I'm going to switch this line to this: const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env || process.env) }; so that its configured by default, but is overridable if someone wanted to. I believe currently there is a subtle bug here where even if you specified the NODE_TEST_CONTEXT variable in the main process, it'd be overridden to child-v8 no matter what.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't fully understand the ask here:

I would suggest, in any case, adding a snapshot test when using this option to cover the E2E once the option has been provided!

Snapshot of what? The environment variables? Do you mean for me to just assert that something such as NODE_TEST_CONTEXT is retained when env option is specified, or something more in depth?

doc/api/test.md Outdated
* `functionCoverage` {number} Require a minimum percent of covered functions. If code
coverage does not reach the threshold specified, the process will exit with code `1`.
**Default:** `0`.
* `env` {Object} Specify environment variables to be passed along to the test process. This options is not compatible with `isolation='none'`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it might be worth specifying here that these variables will override those from the main process

* `functionCoverage` {number} Require a minimum percent of covered functions. If code
coverage does not reach the threshold specified, the process will exit with code `1`.
**Default:** `0`.
* `env` {Object} Specify environment variables to be passed along to the test process.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

env vars are supposed to be inherited, what is the usecase here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They still are by default; this feature is essentially just bubbling up the underlying child_process.spawn() env option.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you are using the run() method multiple times to spawn multiple test processes. And want to be able to specify unique environment variables for each; there currently is no way to do so.

const args = getRunArgs(path, opts);
const stdio = ['pipe', 'pipe', 'pipe'];
const env = { __proto__: null, ...process.env, NODE_TEST_CONTEXT: 'child-v8' };
const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env || process.env) };
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env || process.env) };
const env = { __proto__: null, NODE_TEST_CONTEXT: 'child-v8', ...(opts.env ?? process.env) };

nitpic

@pmarchini pmarchini added the request-ci Add this label to start a Jenkins CI on a PR. label Jan 18, 2026
@github-actions github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jan 18, 2026
@nodejs-github-bot
Copy link
Collaborator

@pmarchini
Copy link
Member

Hey @Ethan-Arrowood, while checking the CI, I noticed failures related to these changes.
Could you please take a look at them?

@Ethan-Arrowood
Copy link
Contributor Author

The only one that isn't a flake or build issue is Linux Containered: https://ci.nodejs.org/job/node-test-commit-linux-containered/54320/

I'm not familiar with this environment, but I will try to take a look.

@Ethan-Arrowood
Copy link
Contributor Author

I am having a hard time understanding why this test is failing on these environments. I'm inspecting the stack trace in Jenkins and its not sharing anything useful:


---
duration_ms: 1248.809
exitcode: 1
severity: fail
stack: |-
  Test failure: 'should allow env variables to be configured'
  Location: test/parallel/test-runner-run.mjs:654:3
  AssertionError [ERR_ASSERTION]: function should not have been called at file:///home/iojs/build/workspace/node-test-commit-linux-containered/test/parallel/test-runner-run.mjs:658
  called with arguments: [Object: null prototype] {
    name: '/home/iojs/build/workspace/node-test-commit-linux-containered/test/fixtures/test-runner/process-env.js',
    nesting: 0,
    testNumber: 1,
    details: [Object: null prototype] {
      duration_ms: 6.408189,
      type: 'test',
      error: [Error: test failed] {
        code: 'ERR_TEST_FAILURE',
        failureType: 'testCodeFailure',
        cause: 'test failed',
        exitCode: 127,
        signal: null
      }
    },
    line: 1,
    column: 1,
    file: '/home/iojs/build/workspace/node-test-commit-linux-containered/test/fixtures/test-runner/process-env.js'
  }
      at TestsStream.mustNotCall (/home/iojs/build/workspace/node-test-commit-linux-containered/test/common/index.js:564:12)
      at TestsStream.emit (node:events:508:20)
      at [kEmitMessage] (node:internal/test_runner/tests_stream:157:10)
      at TestsStream.fail (node:internal/test_runner/tests_stream:38:23)
      at FileTest.report (node:internal/test_runner/test:1384:21)
      at FileTest.report (node:internal/test_runner/runner:307:13)
      at FileTest.finalize (node:internal/test_runner/test:1325:10)
      at Test.processReadySubtestRange (node:internal/test_runner/test:833:15)
      at FileTest.postRun (node:internal/test_runner/test:1237:19)
      at Test.postRun (node:internal/test_runner/test:1210:17) {
    generatedMessage: false,
    code: 'ERR_ASSERTION',
    actual: undefined,
    expected: undefined,
    operator: 'fail',
    diff: 'simple'
  }

  (node:158076) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 uncaughtException listeners added to [process]. MaxListeners is 10. Use emitter.setMaxListeners() to increase limit
  (Use `node --trace-warnings ...` to show where the warning was created)
  (node:158076) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 unhandledRejection listeners added to [process]. MaxListeners is 10. Use emitter.setMaxListeners() to increase limit
  (node:158076) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 beforeExit listeners added to [process]. MaxListeners is 10. Use emitter.setMaxListeners() to increase limit
...

All this stack is telling me is that the stream.on('test:fail', common.mustNotCall()); in the test is being called. But, it is not saying why making me think this is not an actual assertion issue from test/fixtures/test-runner/process-env.js, but possibly something else?

Locally, if I add a line like: t.assert.fail('Intentionally fail test.'); to test/fixtures/test-runner/process-env.js, then the stack trace actually has useful information about whats causing the test to fail:

❯ tools/test.py test/parallel/test-runner-run.mjs
=== release test-runner-run ===                   
Path: parallel/test-runner-run
Test failure: 'should allow env variables to be configured'
Location: test/parallel/test-runner-run.mjs:654:3
AssertionError [ERR_ASSERTION]: function should not have been called at file:///Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs:658
called with arguments: [Object: null prototype] {
  name: '/Users/ethan/dev/nodejs/node/test/fixtures/test-runner/process-env.js',
  nesting: 0,
  testNumber: 1,
  details: [Object: null prototype] {
    duration_ms: 61.008,
    type: 'test',
    error: Error [ERR_TEST_FAILURE]: function should not have been called at file:///Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs:658
    called with arguments: {
      name: 'process.env is correct',
      nesting: 0,
      testNumber: 1,
      details: {
        duration_ms: 1.46075,
        type: 'test',
        error: [Error [ERR_TEST_FAILURE]: Intentionally fail test.] {
          code: 'ERR_TEST_FAILURE',
          failureType: 'testCodeFailure',
          cause: [Error]
        }
      },
      line: 3,
      column: 1,
      file: '/Users/ethan/dev/nodejs/node/test/fixtures/test-runner/process-env.js'
    }
        at process.emit (node:events:520:22)
        at process.emit (node:domain:489:12) {
      code: 'ERR_TEST_FAILURE',
      failureType: 'uncaughtException',
      cause: AssertionError [ERR_ASSERTION]: function should not have been called at file:///Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs:658
      called with arguments: {
        name: 'process.env is correct',
        nesting: 0,
        testNumber: 1,
        details: {
          duration_ms: 1.46075,
          type: 'test',
          error: [Error [ERR_TEST_FAILURE]: Intentionally fail test.] {
            code: 'ERR_TEST_FAILURE',
            failureType: 'testCodeFailure',
            cause: [Error]
          }
        },
        line: 3,
        column: 1,
        file: '/Users/ethan/dev/nodejs/node/test/fixtures/test-runner/process-env.js'
      }
          at TestsStream.mustNotCall (/Users/ethan/dev/nodejs/node/test/common/index.js:564:12)
          at TestsStream.emit (node:events:508:20)
          at TestsStream.emit (node:domain:489:12)
          at [kEmitMessage] (node:internal/test_runner/tests_stream:153:10)
          at #handleReportItem (node:internal/test_runner/runner:272:32)
          at FileTest.addToReport (node:internal/test_runner/runner:296:27)
          at #processRawBuffer (node:internal/test_runner/runner:395:12)
          at FileTest.parseMessage (node:internal/test_runner/runner:329:27)
          at Socket.<anonymous> (node:internal/test_runner/runner:439:15)
          at Socket.emit (node:events:508:20) {
        generatedMessage: false,
        code: 'ERR_ASSERTION',
        actual: undefined,
        expected: undefined,
        operator: 'fail',
        diff: 'simple'
      }
    }
  },
  line: 1,
  column: 1,
  file: '/Users/ethan/dev/nodejs/node/test/fixtures/test-runner/process-env.js'
}
    at TestsStream.mustNotCall (/Users/ethan/dev/nodejs/node/test/common/index.js:564:12)
    at TestsStream.emit (node:events:508:20)
    at TestsStream.emit (node:domain:489:12)
    at [kEmitMessage] (node:internal/test_runner/tests_stream:153:10)
    at TestsStream.fail (node:internal/test_runner/tests_stream:38:23)
    at FileTest.report (node:internal/test_runner/test:1367:21)
    at FileTest.report (node:internal/test_runner/runner:308:13)
    at FileTest.finalize (node:internal/test_runner/test:1311:10)
    at Test.processReadySubtestRange (node:internal/test_runner/test:824:15)
    at FileTest.postRun (node:internal/test_runner/test:1223:19) {
  generatedMessage: false,
  code: 'ERR_ASSERTION',
  actual: undefined,
  expected: undefined,
  operator: 'fail',
  diff: 'simple'
}
Command: out/Release/node --test-reporter=./test/common/test-error-reporter.js --test-reporter-destination=stdout /Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs


[00:00|% 100|+   0|-   1]: Done                   

Failed tests:
out/Release/node --test-reporter=./test/common/test-error-reporter.js --test-reporter-destination=stdout /Users/ethan/dev/nodejs/node/test/parallel/test-runner-run.mjs

Does anyone have a better idea here?

@Ethan-Arrowood
Copy link
Contributor Author

Is the issue that we are not inheriting anything from process.env? Could the Linux Containered environment have a more minimal environment where PATH and other variables are needed? Like the exit code 127 is telling me that this environment cannot find the necessary things to execute.

So following this idea... could the run() implementation have been implicitly relying on something being specified in process.env ? Maybe there is a required fix there 🤔

@Ethan-Arrowood
Copy link
Contributor Author

I prompted AI with that idea and it came up with something by looking at other tests and things. Here is a summary from what it figured out.

The Fix: Added addLibraryPath(env) call in test-runner-run.mjs:661 to ensure the custom environment includes necessary library paths when Node.js is built as a shared library.

Why this approach:

  1. Respects the env API contract: When users provide env, they get exactly what they specify. The test runner doesn't inject variables automatically.
  2. Follows existing patterns: Other Node.js tests that use custom environments (like test-child-process-fork-exec-path.js) also use addLibraryPath() explicitly.
  3. User responsibility: If you're building Node.js as a shared library and providing a custom environment, you need to handle the library paths yourself using the test utility.

This reasoning makes sense to me, but please correct if it was wrong.

@pmarchini pmarchini added the request-ci Add this label to start a Jenkins CI on a PR. label Jan 21, 2026
@github-actions github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jan 21, 2026
@nodejs-github-bot
Copy link
Collaborator

CI: https://ci.nodejs.org/job/node-test-pull-request/70947/

@Ethan-Arrowood
Copy link
Contributor Author

Only flake in the CI 🎉

This is ready to merge I think 🚀

@Ethan-Arrowood
Copy link
Contributor Author

I think we could backport this feature to all active release lines, right? Nothing at all breaking here.

@nodejs-github-bot
Copy link
Collaborator

@Ethan-Arrowood Ethan-Arrowood added author ready PRs that have at least one approval, no pending requests for changes, and a CI started. lts-watch-v24.x PRs that may need to be released in v24.x labels Jan 21, 2026
@pmarchini pmarchini added the commit-queue Add this label to land a pull request using GitHub Actions. label Jan 22, 2026
@nodejs-github-bot nodejs-github-bot added commit-queue-failed An error occurred while landing this pull request using GitHub Actions. and removed commit-queue Add this label to land a pull request using GitHub Actions. labels Jan 22, 2026
@nodejs-github-bot
Copy link
Collaborator

Commit Queue failed
- Loading data for nodejs/node/pull/61367
✔  Done loading data for nodejs/node/pull/61367
----------------------------------- PR info ------------------------------------
Title      test_runner: add env option to run function (#61367)
Author     Ethan Arrowood <ethan@arrowood.dev> (@Ethan-Arrowood)
Branch     Ethan-Arrowood:test-runner-env-option -> nodejs:main
Labels     author ready, needs-ci, test_runner, lts-watch-v24.x
Commits    1
 - test_runner: add env option to run function
Committers 1
 - Ethan Arrowood <ethan@arrowood.dev>
PR-URL: https://github.com/nodejs/node/pull/61367
Fixes: https://github.com/nodejs/node/issues/60709
Reviewed-By: Aviv Keller <me@aviv.sh>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/61367
Fixes: https://github.com/nodejs/node/issues/60709
Reviewed-By: Aviv Keller <me@aviv.sh>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Tue, 13 Jan 2026 14:07:30 GMT
   ✔  Approvals: 4
   ✔  - Aviv Keller (@avivkeller): https://github.com/nodejs/node/pull/61367#pullrequestreview-3665952352
   ✔  - Moshe Atlow (@MoLow): https://github.com/nodejs/node/pull/61367#pullrequestreview-3689596887
   ✔  - Chemi Atlow (@atlowChemi): https://github.com/nodejs/node/pull/61367#pullrequestreview-3674542545
   ✔  - Pietro Marchini (@pmarchini): https://github.com/nodejs/node/pull/61367#pullrequestreview-3688920854
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2026-01-21T21:24:34Z: https://ci.nodejs.org/job/node-test-pull-request/70950/
- Querying data for job/node-test-pull-request/70950/
✔  Build data downloaded
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 61367
From https://github.com/nodejs/node
 * branch                  refs/pull/61367/merge -> FETCH_HEAD
✔  Fetched commits as 9e201e61fd8e..2ce1c301bbe2
--------------------------------------------------------------------------------
Auto-merging doc/api/test.md
Auto-merging lib/internal/test_runner/runner.js
Auto-merging test/parallel/test-runner-run.mjs
[main d32b813a93] test_runner: add env option to run function
 Author: Ethan Arrowood <ethan@arrowood.dev>
 Date: Tue Jan 13 07:04:26 2026 -0700
 4 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 test/fixtures/test-runner/process-env.js
   ✔  Patches applied
--------------------------------------------------------------------------------
   ✘  Git found no trailers in the original commit message, but 'Fixes: https://github.com/nodejs/node/issues/60709' is present and should be a trailer.
https://github.com/nodejs/node/actions/runs/21241113410

Support an `env` option that is passed to the underlying child_process.

Fixes: nodejs#60709
@Ethan-Arrowood
Copy link
Contributor Author

Silly new line lol

@Ethan-Arrowood Ethan-Arrowood added the semver-minor PRs that contain new features and should be released in the next minor version. label Jan 22, 2026
@MoLow MoLow added request-ci Add this label to start a Jenkins CI on a PR. and removed commit-queue-failed An error occurred while landing this pull request using GitHub Actions. labels Jan 22, 2026
@github-actions github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jan 22, 2026
@nodejs-github-bot
Copy link
Collaborator

@nodejs-github-bot
Copy link
Collaborator

Copy link
Member

@mcollina mcollina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@Ethan-Arrowood Ethan-Arrowood added the request-ci Add this label to start a Jenkins CI on a PR. label Jan 23, 2026
@github-actions github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jan 23, 2026
@nodejs-github-bot
Copy link
Collaborator

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author ready PRs that have at least one approval, no pending requests for changes, and a CI started. lts-watch-v24.x PRs that may need to be released in v24.x needs-ci PRs that need a full CI run. semver-minor PRs that contain new features and should be released in the next minor version. test_runner Issues and PRs related to the test runner subsystem.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Test Runner run() should support env option

8 participants